Snotify Codebase Architecture & Product Overview

1. Product Vision
2. High-Level Architecture
- 2.1. System Overview (Mermaid Diagram)
- 2.2. Key Technologies
3. Backend Architecture
4. Frontend Architecture
5. Developer Experience
6. Product Management View
7. Security & Compliance
8. Extensibility & Future Roadmap

1. Product Vision

Snotify is a modern, maintainable music storage and player application with playlists, albums, and a blog. It features a responsive, user-friendly UI, secure JWT authentication, and stores all media as files (not blobs) for performance and simplicity. The app is designed for easy extensibility and robust user experience.

2. High-Level Architecture

2.1. System Overview (Mermaid Diagram)

graph TD
  subgraph Frontend ["React App"]
    A1[AuthContext]
    A2[Album Grid]
    A3[Album Details]
    A4[Track Upload Dialog]
    A5[Player]
    A6[Sidebar/Topbar]
    A7[Blog/Playlists]
  end
  
  subgraph Backend ["Node.js/Express"]
    B1[Auth Routes]
    B2[Album Routes]
    B3[Track Routes]
    B4[Playlist Routes]
    B5[Blog Routes]
    B6[Static File Server]
    B7[Prisma ORM]
  end
  
  subgraph Database ["MySQL"]
    D1[User]
    D2[Album]
    D3[Song]
    D4[Playlist]
    D5[BlogPost]
    D6[PlaylistSong]
  end
  
  subgraph Storage ["Filesystem"]
    S1["uploads/albums/&lt;album_id&gt;/tracks/"]
    S2["uploads/&lt;album_name&gt;/cover.jpg"]
  end
  
  A1 -->|JWT| B1
  A2 -->|REST| B2
  A3 -->|REST| B2
  A4 -->|"REST (multipart/form-data)"| B3
  A5 -->|Audio URLs| S1
  A6 -->|Navigation| A2
  A7 -->|REST| B5
  
  B1 -->|Prisma| B7
  B2 -->|Prisma| B7
  B3 -->|Prisma| B7
  B4 -->|Prisma| B7
  B5 -->|Prisma| B7
  
  B7 -->|SQL| D1
  B7 -->|SQL| D2
  B7 -->|SQL| D3
  B7 -->|SQL| D4
  B7 -->|SQL| D5
  B7 -->|SQL| D6
  
  B2 -->|File Paths| S2
  B3 -->|File Paths| S1
  B6 -->|Serve Files| S1
  B6 -->|Serve Files| S2

2.2. Key Technologies

Frontend: React, TypeScript, shadcn/ui, Heroicons/lucide-react, React Context, React Router
Backend: Node.js, Express, Prisma ORM, JWT, Multer, music-metadata
Database: MySQL (Prisma-managed)
Storage: Filesystem (uploads directory, paths in DB)
Testing: (Recommend: Jest, React Testing Library)
Styling: Tailwind CSS

3. Backend Architecture

3.1. Database Schema (Prisma)

User: Auth, owns playlists and blog posts.
Album: Title, artist, image path, year, track count, duration.
Song: Title, artist, file path, album, duration, genre.
Playlist: Name, user, many-to-many with songs.
BlogPost: Title, content, user.
PlaylistSong: Join table for playlists and songs.

erDiagram
  USER ||--o{ PLAYLIST : owns
  USER ||--o{ BLOGPOST : writes
  ALBUM ||--o{ SONG : contains
  PLAYLIST ||--o{ PLAYLISTSONG : has
  SONG ||--o{ PLAYLISTSONG : in

3.2. API Routing & Logic

/api/auth: Register, login (JWT), health check.
/api/albums: CRUD for albums, image upload (multer), fetch by artist.
/api/albums/:id: Get album details.
/api/albums/:albumId/tracks: Upload track (multer), fetch tracks.
/api/playlists, /api/blog: CRUD stubs.

Routing Example:

graph TD
FE[Frontend] -- POST /api/albums --> BE[Backend]
BE -- Prisma --> DB[(MySQL)]
BE -- File Upload --> FS[(Filesystem)]

3.3. File Storage

Images: uploads/<album_name>/cover.jpg
Tracks: uploads/albums/<album_id>/tracks/<unique>.mp3
DB: Only relative file paths stored.
Static Serving: Express serves /uploads as static.

3.4. Authentication

JWT-based: Register/login endpoints, tokens stored in localStorage.
Password Hashing: bcryptjs.
Token Verification: Middleware for protected routes (future extensibility).

4. Frontend Architecture

4.1. UI Structure

Sidebar: Navigation, responsive, collapsible, keyboard shortcut.
Top Bar: (Planned/partial) for quick actions, user info.
Main Content: Album grid, album details, blog, playlists.
Dialogs: Add album, add track, update album art.
Player: Fixed bottom, plays selected track.

graph TD
  Sidebar --nav--> MainContent
  MainContent --select--> Dialogs
  MainContent --play--> Player

4.2. State Management

AuthContext: Handles user state, login, logout, registration.
Local State: Album/tracks/related loading, error, selection.
Toasts: Feedback for actions (success/error).

4.3. Responsive Design

shadcn/ui: Modern, accessible, mobile-first.
Tailwind CSS: Utility classes for layout, color, spacing.
Sidebar: Collapses on mobile, uses Sheet for drawer.
Album Grid: Responsive columns, cards adapt to screen size.

5. Developer Experience

TypeScript: Type safety throughout (types, interfaces, zod validation).
Prisma: Type-safe DB access, easy migrations, seed scripts.
Modular Components: UI split into logical, reusable pieces.
Hooks: Custom hooks for album data, audio, mobile detection.
.env Config: Uploads path, JWT secret, DB URL.
Testing: (Recommend adding unit/integration tests for all CRUD and UI flows.)

6. Product Management View

Core Features:
- User registration/login (JWT)
- Album CRUD with image upload
- Track upload (mp3/m4a), duration extraction
- Playlist and blog (CRUD stubs)
- Responsive, modern UI
User Stories:
- As a user, I can browse albums and see cover art.
- As a user, I can view album details and play tracks.
- As a user, I can upload new albums and tracks.
- As a user, I can manage playlists and read blog posts.
KPIs:
- Upload success rate
- Track play reliability
- Auth/session security
- Mobile usability

7. Security & Compliance

Passwords: Hashed with bcryptjs.
JWT: Signed with secret, expiry set.
Uploads: Only file paths in DB, files stored outside web root.
Validation: zod for forms, server-side checks for required fields.
Error Handling: Robust try/catch, user feedback via toasts.
Edge Cases: Handles missing files, invalid IDs, duplicate users.

8. Extensibility & Future Roadmap

Planned/Recommended:
- Full CRUD for playlists and blog.
- User roles/permissions.
- Track reordering, album editing.
- Search and filter for albums/tracks.
- Social features (sharing, comments).
- API rate limiting, audit logging.
- Automated tests (Jest, Cypress).
- CI/CD integration.